<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">











<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Math - The Commons Math User Guide - Geometry</title>
    <style type="text/css" media="all">
      @import url("../css/maven-base.css");
      @import url("../css/maven-theme.css");
      @import url("../css/site.css");
    </style>
    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
      </head>
  <body class="composite">
    <div id="banner">
                    <span id="bannerLeft">
    
            Commons Math User Guide
    
            </span>
                    <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="breadcrumbs">
          
  

  
    
  
  
    
              <div class="xright">      
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
           
  

  
    
  
  
    
                   <h5>User Guide</h5>
            <ul>
              
    <li class="none">
                    <a href="../userguide/index.html">Contents</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/overview.html">Overview</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/stat.html">Statistics</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/random.html">Data Generation</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/linear.html">Linear Algebra</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/analysis.html">Numerical Analysis</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/special.html">Special Functions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/utilities.html">Utilities</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/complex.html">Complex Numbers</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/distribution.html">Distributions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/fraction.html">Fractions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/transform.html">Transform Methods</a>
          </li>
              
    <li class="none">
              <strong>3D Geometry</strong>
        </li>
              
    <li class="none">
                    <a href="../userguide/optimization.html">Optimization</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/ode.html">Ordinary Differential Equations</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/genetics.html">Genetic Algorithms</a>
          </li>
          </ul>
                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
          </a>
                       
  

  
    
  
  
    
        </div>
    </div>
    <div id="bodyColumn">
      <div id="contentBox">
        <div class="section"><h2><a name="a11_Geometry"></a>
11 Geometry</h2>
<div class="section"><h3><a name="a11.1_Overview"></a>
11.1 Overview</h3>
<p>
           The geometry package provides classes useful for many physical simulations
           in the real 3D space, namely vectors and rotations.
        </p>
</div>
<div class="section"><h3><a name="a11.2_Vectors"></a>
11.2 Vectors</h3>
<p><a href="../apidocs/org/apache/commons/math/geometry/Vector3D.html">
          org.apache.commons.math.geometry.Vector3D</a>
 provides a simple vector
          type. One important feature is that instances of this class are guaranteed
          to be immutable, this greatly simplifies modelling dynamical systems
          with changing states: once a vector has been computed, a reference to it
          is known to preserve its state as long as the reference itself is preserved.
        </p>
<p>
          Numerous constructors are available to create vectors. In addition to the
          straightforward cartesian coordinates constructor, a constructor using
          azimuthal coordinates can build normalized vectors and linear constructors
          from one, two, three or four base vectors are also available. Constants have
          been defined for the most commons vectors (plus and minus canonical axes,
          null vector, and special vectors with infinite or NaN coordinates).
        </p>
<p>
          The generic vectorial space operations are available including dot product,
          normalization, orthogonal vector finding and angular separation computation
          which have a specific meaning in 3D. The 3D geometry specific cross product
          is of course also implemented.
        </p>
<p><a href="../apidocs/org/apache/commons/math/geometry/Vector3DFormat.html">
          org.apache.commons.math.geometry.Vector3DFormat</a>
 is a specialized format
          for formatting output or parsing input with text representation of 3D vectors.
        </p>
</div>
<div class="section"><h3><a name="a11.3_Rotations"></a>
11.3 Rotations</h3>
<p><a href="../apidocs/org/apache/commons/math/geometry/Rotation.html">
          org.apache.commons.math.geometry.Rotation</a>
 represents 3D rotations.
          Rotation instances are also immutable objects, as Vector3D instances.
        </p>
<p>
          Rotations can be represented by several different mathematical
          entities (matrices, axe and angle, Cardan or Euler angles,
          quaternions). This class presents a higher level abstraction, more
          user-oriented and hiding implementation details. Well, for the
          curious, we use quaternions for the internal representation. The user
          can build a rotation from any of these representations, and any of
          these representations can be retrieved from a <code>Rotation</code>
          instance (see the various constructors and getters). In addition, a
          rotation can also be built implicitely from a set of vectors and their
          image.
        </p>
<p>
          This implies that this class can be used to convert from one
          representation to another one. For example, converting a rotation
          matrix into a set of Cardan angles can be done using the
          following single line of code:
        </p>
<div class="source"><pre>double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ);</pre>
</div>
<p>
          Focus is oriented on what a rotation <em>does</em> rather than on its
          underlying representation. Once it has been built, and regardless of
          its internal representation, a rotation is an <em>operator</em> which
          basically transforms three dimensional vectors into other three
          dimensional vectors. Depending on the application, the meaning of
          these vectors may vary as well as the semantics of the rotation.
        </p>
<p>
          For example in a spacecraft attitude simulation tool, users will
          often consider the vectors are fixed (say the Earth direction for
          example) and the rotation transforms the coordinates coordinates of
          this vector in inertial frame into the coordinates of the same vector
          in satellite frame. In this case, the rotation implicitly defines the
          relation between the two frames (we have fixed vectors and moving frame).
          Another example could be a telescope control application, where the
          rotation would transform the sighting direction at rest into the desired
          observing direction when the telescope is pointed towards an object of
          interest. In this case the rotation transforms the direction at rest in
          a topocentric frame into the sighting direction in the same topocentric
          frame (we have moving vectors in fixed frame). In many case, both
          approaches will be combined, in our telescope example, we will probably
          also need to transform the observing direction in the topocentric frame
          into the observing direction in inertial frame taking into account the
          observatory location and the Earth rotation.
        </p>
<p>
          These examples show that a rotation means what the user wants it to
          mean, so this class does not push the user towards one specific
          definition and hence does not provide methods like
          <code>projectVectorIntoDestinationFrame</code> or
          <code>computeTransformedDirection</code>. It provides simpler and more
          generic methods: <code>applyTo(Vector3D)</code> and
          <code>applyInverseTo(Vector3D)</code>.
        </p>
<p>
          Since a rotation is basically a vectorial operator, several
          rotations can be composed together and the composite operation
          <code>r = r<sub>1</sub> o r<sub>2</sub></code> (which means that for each
          vector <code>u</code>, <code>r(u) = r<sub>1</sub>(r<sub>2</sub>(u))</code>)
          is also a rotation. Hence we can consider that in addition to vectors, a
          rotation can be applied to other rotations as well (or to itself). With our
          previous notations, we would say we can apply <code>r<sub>1</sub></code> to
          <code>r<sub>2</sub></code> and the result we get is <code>r =
          r<sub>1</sub> o r<sub>2</sub></code>. For this purpose, the class
          provides the methods: <code>applyTo(Rotation)</code> and
          <code>applyInverseTo(Rotation)</code>.
        </p>
</div>
</div>

      </div>
    </div>
    <div class="clear">
      <hr/>
    </div>
    <div id="footer">
      <div class="xright">&#169;  
          2003-2009
    
          
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
  </body>
</html>
